/**
 * Copyright 2006 gworks.com.au
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. (http://www.apache.org/licenses/LICENSE-2.0)
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed 
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for 
 * the specific language governing permissions and limitations under the License.
 *
 * <dhamma-message src="Atisha (11th century Tibetan Buddhist master)">
 * 	The greatest achievement is selflessness. The greatest worth is self-mastery.
 * 	The greatest quality is seeking to serve others. The greatest precept is continual awareness.
 * 	The greatest medicine is the emptiness of everything. The greatest action is not conforming with the worlds ways.
 * 	The greatest magic is transmuting the passions. The greatest generosity is non-attachment.
 * 	The greatest goodness is a peaceful mind. The greatest patience is humility.
 * 	The greatest effort is not concerned with results. The greatest meditation is a mind that lets go.
 * 	The greatest wisdom is seeing through appearances. 
 * </dhamma-message>
 */
package org.javaongems.client.rt.io;

import java.util.HashMap;
import java.util.Map;

import com.google.gwt.user.client.rpc.AsyncCallback;

/**
 * <p>Provides the ability to decorate AsyncCallbacks.</p>
 * <p>Responsibilities:
 * <ul>
 * 	<li> query a decoration from somewhere in the layers
 * 	<li> maintain a single registry of decorations applied
 *  <li> wrap the delegates async callback behaviour
 * </ul>
 * </p>
 * <p>Constraints:
 * <ul>
 * 	<li> GWT emulation subsystem
 * 	<li> GWT compiler does not support Java generics
 * </ul>
 * </p>
 * @author Ashin Wimalajeewa (ash)
 */
public class AsyncCallbackFilter implements AsyncCallback {
	protected AsyncCallback delegate;
	protected Map layers;	

	public AsyncCallbackFilter(AsyncCallback toWrap) {
		delegate = toWrap;
		layers = prepareCommonDecorationRegistry(toWrap);
		layers.put(getHandle(), this);
	}

	/**
	 * Command that queries or constructs the shared decoration registry.
	 * @param toWrap - the Async callback that is wrapped
	 * @return the common decoration registry
	 */
	protected Map prepareCommonDecorationRegistry(AsyncCallback toWrap) {
		Map ret;
		if (toWrap instanceof AsyncCallbackFilter) {
			AsyncCallbackFilter innerLayer = (AsyncCallbackFilter) toWrap;
			ret = innerLayer.getLayers();
		} else
			ret = new HashMap();
		return ret;
	}
	
	/**
	 * Query the unique handle that is associated with the decoration type. 
	 * Gem Application developer will use this handle to configure decorations  
	 * post creation.
	 * @return a unique handle name
	 * @see #getDecoration(String)
	 */
	public String getHandle() {
		return "base";
	}
	
	/**
	 * @see com.google.gwt.user.client.rpc.AsyncCallback#onFailure(java.lang.Throwable)
	 */
	public void onFailure(Throwable caught) {
		delegate.onFailure(caught);
	}

	/** 
	 * @see com.google.gwt.user.client.rpc.AsyncCallback#onSuccess(java.lang.Object)
	 */
	public void onSuccess(Object result) {
		delegate.onSuccess(result);
	}
	
	/**
	 * Queries the common decoration registry for the async callback decoration.
	 * @param handle - named handle used to identify the decoration
	 * @return the decoration associated to the handle
	 * @see #getHandle()
	 */
	public AsyncCallbackFilter getDecoration(String handle) {
		return (AsyncCallbackFilter) layers.get(handle);
	}
	
	/**
	 * Query that returns the common decorations registry
	 * @return a map of all decorations applied to the root Async callback object
	 */
	protected Map getLayers() {
		return layers;
	}
}
